<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><link rel="stylesheet" type="text/css" href="style.css" /><script type="text/javascript" src="highlight.js"></script></head><body><pre><span class="hs-pragma">{-# LANGUAGE Trustworthy #-}</span><span>
</span><span id="line-2"></span><span class="hs-pragma">{-# LANGUAGE NoImplicitPrelude #-}</span><span>
</span><span id="line-3"></span><span>
</span><span id="line-4"></span><span class="hs-comment">-----------------------------------------------------------------------------</span><span>
</span><span id="line-5"></span><span class="hs-comment">-- |</span><span>
</span><span id="line-6"></span><span class="hs-comment">-- Module      :  Foreign.Concurrent</span><span>
</span><span id="line-7"></span><span class="hs-comment">-- Copyright   :  (c) The University of Glasgow 2003</span><span>
</span><span id="line-8"></span><span class="hs-comment">-- License     :  BSD-style (see the file libraries/base/LICENSE)</span><span>
</span><span id="line-9"></span><span class="hs-comment">-- </span><span>
</span><span id="line-10"></span><span class="hs-comment">-- Maintainer  :  ffi@haskell.org</span><span>
</span><span id="line-11"></span><span class="hs-comment">-- Stability   :  provisional</span><span>
</span><span id="line-12"></span><span class="hs-comment">-- Portability :  non-portable (requires concurrency)</span><span>
</span><span id="line-13"></span><span class="hs-comment">--</span><span>
</span><span id="line-14"></span><span class="hs-comment">-- FFI datatypes and operations that use or require concurrency (GHC only).</span><span>
</span><span id="line-15"></span><span class="hs-comment">--</span><span>
</span><span id="line-16"></span><span class="hs-comment">-----------------------------------------------------------------------------</span><span>
</span><span id="line-17"></span><span>
</span><span id="line-18"></span><span class="hs-keyword">module</span><span> </span><span class="hs-identifier">Foreign.Concurrent</span><span>
</span><span id="line-19"></span><span>  </span><span class="hs-special">(</span><span>
</span><span id="line-20"></span><span>        </span><span class="annot"><span class="hs-comment">-- * Concurrency-based 'ForeignPtr' operations</span></span><span>
</span><span id="line-21"></span><span>
</span><span id="line-22"></span><span>        </span><span class="hs-comment">-- | These functions generalize their namesakes in the portable</span><span>
</span><span id="line-23"></span><span>        </span><span class="hs-comment">-- &quot;Foreign.ForeignPtr&quot; module by allowing arbitrary 'IO' actions</span><span>
</span><span id="line-24"></span><span>        </span><span class="hs-comment">-- as finalizers.  These finalizers necessarily run in a separate</span><span>
</span><span id="line-25"></span><span>        </span><span class="hs-comment">-- thread, cf. /Destructors, Finalizers and Synchronization/,</span><span>
</span><span id="line-26"></span><span>        </span><span class="hs-comment">-- by Hans Boehm, /POPL/, 2003.</span><span>
</span><span id="line-27"></span><span>
</span><span id="line-28"></span><span>        </span><span class="annot"><a href="Foreign.Concurrent.html#newForeignPtr"><span class="hs-identifier">newForeignPtr</span></a></span><span class="hs-special">,</span><span>
</span><span id="line-29"></span><span>        </span><span class="annot"><a href="Foreign.Concurrent.html#addForeignPtrFinalizer"><span class="hs-identifier">addForeignPtrFinalizer</span></a></span><span class="hs-special">,</span><span>
</span><span id="line-30"></span><span>  </span><span class="hs-special">)</span><span> </span><span class="hs-keyword">where</span><span>
</span><span id="line-31"></span><span>
</span><span id="line-32"></span><span class="hs-keyword">import</span><span> </span><span class="annot"><a href="GHC.IO.html"><span class="hs-identifier">GHC.IO</span></a></span><span>         </span><span class="hs-special">(</span><span> </span><span class="annot"><a href="../../ghc-prim/src/GHC.Types.html#IO"><span class="hs-identifier">IO</span></a></span><span> </span><span class="hs-special">)</span><span>
</span><span id="line-33"></span><span class="hs-keyword">import</span><span> </span><span class="annot"><a href="GHC.Ptr.html"><span class="hs-identifier">GHC.Ptr</span></a></span><span>        </span><span class="hs-special">(</span><span> </span><span class="annot"><a href="GHC.Ptr.html#Ptr"><span class="hs-identifier">Ptr</span></a></span><span> </span><span class="hs-special">)</span><span>
</span><span id="line-34"></span><span class="hs-keyword">import</span><span> </span><span class="annot"><a href="GHC.ForeignPtr.html"><span class="hs-identifier">GHC.ForeignPtr</span></a></span><span> </span><span class="hs-special">(</span><span> </span><span class="annot"><a href="GHC.ForeignPtr.html#ForeignPtr"><span class="hs-identifier">ForeignPtr</span></a></span><span> </span><span class="hs-special">)</span><span>
</span><span id="line-35"></span><span class="hs-keyword">import</span><span> </span><span class="hs-keyword">qualified</span><span> </span><span class="annot"><a href="GHC.ForeignPtr.html"><span class="hs-identifier">GHC.ForeignPtr</span></a></span><span>
</span><span id="line-36"></span><span>
</span><span id="line-37"></span><span id="local-6989586621679562609"><span class="annot"><a href="Foreign.Concurrent.html#newForeignPtr"><span class="hs-identifier hs-type">newForeignPtr</span></a></span><span> </span><span class="hs-glyph">::</span><span> </span><span class="annot"><a href="GHC.Ptr.html#Ptr"><span class="hs-identifier hs-type">Ptr</span></a></span><span> </span><span class="annot"><a href="#local-6989586621679562609"><span class="hs-identifier hs-type">a</span></a></span><span> </span><span class="hs-glyph">-&gt;</span><span> </span><span class="annot"><a href="../../ghc-prim/src/GHC.Types.html#IO"><span class="hs-identifier hs-type">IO</span></a></span><span> </span><span class="hs-special">(</span><span class="hs-special">)</span><span> </span><span class="hs-glyph">-&gt;</span><span> </span><span class="annot"><a href="../../ghc-prim/src/GHC.Types.html#IO"><span class="hs-identifier hs-type">IO</span></a></span><span> </span><span class="hs-special">(</span><span class="annot"><a href="GHC.ForeignPtr.html#ForeignPtr"><span class="hs-identifier hs-type">ForeignPtr</span></a></span><span> </span><span class="annot"><a href="#local-6989586621679562609"><span class="hs-identifier hs-type">a</span></a></span><span class="hs-special">)</span></span><span>
</span><span id="line-38"></span><span class="hs-comment">--</span><span>
</span><span id="line-39"></span><span class="hs-comment">-- ^Turns a plain memory reference into a foreign object by</span><span>
</span><span id="line-40"></span><span class="hs-comment">-- associating a finalizer - given by the monadic operation - with the</span><span>
</span><span id="line-41"></span><span class="hs-comment">-- reference.  The storage manager will start the finalizer, in a</span><span>
</span><span id="line-42"></span><span class="hs-comment">-- separate thread, some time after the last reference to the</span><span>
</span><span id="line-43"></span><span class="hs-comment">-- 'ForeignPtr' is dropped.  There is no guarantee of promptness, and</span><span>
</span><span id="line-44"></span><span class="hs-comment">-- in fact there is no guarantee that the finalizer will eventually</span><span>
</span><span id="line-45"></span><span class="hs-comment">-- run at all.</span><span>
</span><span id="line-46"></span><span class="hs-comment">--</span><span>
</span><span id="line-47"></span><span class="hs-comment">-- Note that references from a finalizer do not necessarily prevent</span><span>
</span><span id="line-48"></span><span class="hs-comment">-- another object from being finalized.  If A's finalizer refers to B</span><span>
</span><span id="line-49"></span><span class="hs-comment">-- (perhaps using 'Foreign.ForeignPtr.touchForeignPtr', then the only</span><span>
</span><span id="line-50"></span><span class="hs-comment">-- guarantee is that B's finalizer will never be started before A's.  If both</span><span>
</span><span id="line-51"></span><span class="hs-comment">-- A and B are unreachable, then both finalizers will start together.  See</span><span>
</span><span id="line-52"></span><span class="hs-comment">-- 'Foreign.ForeignPtr.touchForeignPtr' for more on finalizer ordering.</span><span>
</span><span id="line-53"></span><span class="hs-comment">--</span><span>
</span><span id="line-54"></span><span id="newForeignPtr"><span class="annot"><span class="annottext">newForeignPtr :: forall a. Ptr a -&gt; IO () -&gt; IO (ForeignPtr a)
</span><a href="Foreign.Concurrent.html#newForeignPtr"><span class="hs-identifier hs-var hs-var">newForeignPtr</span></a></span></span><span> </span><span class="hs-glyph">=</span><span> </span><span class="annot"><span class="annottext">Ptr a -&gt; IO () -&gt; IO (ForeignPtr a)
forall a. Ptr a -&gt; IO () -&gt; IO (ForeignPtr a)
</span><a href="GHC.ForeignPtr.html#newConcForeignPtr"><span class="hs-identifier hs-var">GHC.ForeignPtr.newConcForeignPtr</span></a></span><span>
</span><span id="line-55"></span><span>
</span><span id="line-56"></span><span id="local-6989586621679562606"><span class="annot"><a href="Foreign.Concurrent.html#addForeignPtrFinalizer"><span class="hs-identifier hs-type">addForeignPtrFinalizer</span></a></span><span> </span><span class="hs-glyph">::</span><span> </span><span class="annot"><a href="GHC.ForeignPtr.html#ForeignPtr"><span class="hs-identifier hs-type">ForeignPtr</span></a></span><span> </span><span class="annot"><a href="#local-6989586621679562606"><span class="hs-identifier hs-type">a</span></a></span><span> </span><span class="hs-glyph">-&gt;</span><span> </span><span class="annot"><a href="../../ghc-prim/src/GHC.Types.html#IO"><span class="hs-identifier hs-type">IO</span></a></span><span> </span><span class="hs-special">(</span><span class="hs-special">)</span><span> </span><span class="hs-glyph">-&gt;</span><span> </span><span class="annot"><a href="../../ghc-prim/src/GHC.Types.html#IO"><span class="hs-identifier hs-type">IO</span></a></span><span> </span><span class="hs-special">(</span><span class="hs-special">)</span></span><span>
</span><span id="line-57"></span><span class="hs-comment">-- ^This function adds a finalizer to the given 'ForeignPtr'.  The</span><span>
</span><span id="line-58"></span><span class="hs-comment">-- finalizer will run /before/ all other finalizers for the same</span><span>
</span><span id="line-59"></span><span class="hs-comment">-- object which have already been registered.</span><span>
</span><span id="line-60"></span><span class="hs-comment">--</span><span>
</span><span id="line-61"></span><span class="hs-comment">-- This is a variant of 'Foreign.ForeignPtr.addForeignPtrFinalizer',</span><span>
</span><span id="line-62"></span><span class="hs-comment">-- where the finalizer is an arbitrary 'IO' action.  When it is</span><span>
</span><span id="line-63"></span><span class="hs-comment">-- invoked, the finalizer will run in a new thread.</span><span>
</span><span id="line-64"></span><span class="hs-comment">--</span><span>
</span><span id="line-65"></span><span class="hs-comment">-- NB. Be very careful with these finalizers.  One common trap is that</span><span>
</span><span id="line-66"></span><span class="hs-comment">-- if a finalizer references another finalized value, it does not</span><span>
</span><span id="line-67"></span><span class="hs-comment">-- prevent that value from being finalized.  In particular, 'System.IO.Handle's</span><span>
</span><span id="line-68"></span><span class="hs-comment">-- are finalized objects, so a finalizer should not refer to a</span><span>
</span><span id="line-69"></span><span class="hs-comment">-- 'System.IO.Handle' (including 'System.IO.stdout', 'System.IO.stdin', or</span><span>
</span><span id="line-70"></span><span class="hs-comment">-- 'System.IO.stderr').</span><span>
</span><span id="line-71"></span><span class="hs-comment">--</span><span>
</span><span id="line-72"></span><span id="addForeignPtrFinalizer"><span class="annot"><span class="annottext">addForeignPtrFinalizer :: forall a. ForeignPtr a -&gt; IO () -&gt; IO ()
</span><a href="Foreign.Concurrent.html#addForeignPtrFinalizer"><span class="hs-identifier hs-var hs-var">addForeignPtrFinalizer</span></a></span></span><span> </span><span class="hs-glyph">=</span><span> </span><span class="annot"><span class="annottext">ForeignPtr a -&gt; IO () -&gt; IO ()
forall a. ForeignPtr a -&gt; IO () -&gt; IO ()
</span><a href="GHC.ForeignPtr.html#addForeignPtrConcFinalizer"><span class="hs-identifier hs-var">GHC.ForeignPtr.addForeignPtrConcFinalizer</span></a></span><span>
</span><span id="line-73"></span><span>
</span><span id="line-74"></span></pre></body></html>